HERD integration: brain-region ontology terms (Allen Mouse Brain Atlas)#1776
Open
bendichter wants to merge 8 commits into
Open
HERD integration: brain-region ontology terms (Allen Mouse Brain Atlas)#1776bendichter wants to merge 8 commits into
bendichter wants to merge 8 commits into
Conversation
For a mouse subject, resolve anatomical location strings (electrodes table location column, ElectrodeGroup.location, ImagingPlane.location) to Allen Mouse Brain Atlas terms and attach machine-readable MBA references in-file via HDMF's HERD. Locations are resolved first against a user-defined metadata["BrainRegions"] mapping and then against a curated offline lookup of common mouse structures; unrecognized regions can be annotated by defining the mapping in metadata. Gated on species == Mus musculus. Wired into BaseDataInterface/NWBConverter create_nwbfile and the in-memory write path so it runs after electrodes/imaging planes are populated. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
for more information, see https://pre-commit.ci
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Codecov Report❌ Patch coverage is Additional details and impacted files@@ Coverage Diff @@
## add-species-herd-ontology #1776 +/- ##
=============================================================
+ Coverage 82.51% 82.63% +0.11%
=============================================================
Files 179 180 +1
Lines 14080 14193 +113
=============================================================
+ Hits 11618 11728 +110
- Misses 2462 2465 +3
Flags with carried forward coverage won't be shown. Click here to find out more.
🚀 New features to boost your workflow:
|
… overridable hook
- metadata["BrainRegions"] now maps a brain area to explicit ontology
term(s) as {"id", "uri"} (or a list of them), so it is ontology-agnostic
and applies to any species, not just mouse via MBA. A single area can map
to multiple ontologies (e.g. MBA + UBERON); each term shares one HERD key.
- The offline Allen Mouse Brain Atlas lookup remains mouse-gated; the metadata
mapping is not gated on species.
- Annotation is now an overridable method, add_brain_region_external_resources,
provided to BaseDataInterface and NWBConverter via BrainRegionAnnotationMixin.
- Removed brain_region_term_from_identifier (metadata now carries the uri).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…ionMixin Rename BrainRegionAnnotationMixin to OntologyAnnotationMixin and give it two overridable methods, add_species_external_resource and add_brain_region_external_resources, both inherited by BaseDataInterface and NWBConverter and called at write time (create_nwbfile and the in-memory write path). Species HERD annotation is moved out of make_nwbfile_from_metadata into this mixin so it is overridable alongside brain regions; the non-blocking validate_species suggestion still runs in make_nwbfile_from_metadata. Note: standalone tools.spikeinterface/roiextractors write_*_to_nwbfile functions, which build a file via make_nwbfile_from_metadata without an interface, no longer auto-attach the species reference. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Merge docs/user_guide/species_ontology.rst and brain_region_ontology.rst into a single docs/user_guide/ontology.rst covering both annotations and the shared OntologyAnnotationMixin; update the toctree and changelog reference. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…ermSet files Brain-region annotation now supports human subjects: for Homo sapiens, locations resolve against the Allen Human Brain Atlas (HBA), mirroring the mouse MBA path. The lookup is species-specific since acronyms collide across atlases (e.g. MB is the mouse midbrain but the human mammillary body). The species, mouse, and human controlled vocabularies now live in curated LinkML TermSet YAML files (term_sets/*.yaml) — the same format as HDMF's TermSet — read directly with PyYAML, so no linkml-runtime dependency is added. get_brain_region_term gains a species argument; SUPPORTED_ATLAS_SPECIES lists species with an offline atlas. The conversion pipeline (OntologyAnnotationMixin, write-time hooks, metadata BrainRegions mapping, HERD wiring) is unchanged. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Builds on the species HERD work (#1772). Stacked on
add-species-herd-ontologyso the diff shows only the brain-region changes; retarget/rebase ontomainonce #1772 merges.What
Extends
neuroconv.tools.ontologyso that, for a mouse subject, anatomicallocationstrings are annotated with machine-readable Allen Mouse Brain Atlas (MBA) references stored in-file via HDMF's HERD. Downstream tools (e.g. DANDI) can then resolve the exact brain structure instead of guessing from an acronym.Two-step resolution per distinct
locationstring:metadata["BrainRegions"]maps a location string to an MBA identifier — a CURIE ("MBA:382"), bare id ("382"), full URI, or a dict withmba_idand optionalacronym/name. This is how a user annotates a region the offline table doesn't recognize, or overrides one it does."CA1","VISp"), a canonical structure name ("caudoputamen"), or a common informal name/abbreviation ("hippocampus","V1").Locations resolving to neither (including the
"unknown"placeholder) are left untouched. The whole pass is a no-op for non-mouse subjects (the MBA vocabulary is mouse-specific), gated via the existing species resolver.Where it's annotated
locationcolumn (ecephys)ElectrodeGroup.locationImagingPlane.location(ophys)Notes
create_nwbfilefor bothBaseDataInterfaceandNWBConverter, and the in-memoryrun_conversionpath) — after interfaces populate the electrodes table and imaging planes, unlike species annotation which can run at file creation. Idempotent and extends a pre-existingexternal_resourcesHERD in place, so it composes with the species reference.https://purl.brain-bican.org/ontology/mbao/MBA_<id>) were verified against the Allen CCFv3 structure graph, not hardcoded from memory.Testing
tests/test_minimal/test_tools/test_ontology_brain_regions.py— table integrity, acronym/name/alias resolution, case-sensitivity, identifier parsing.tests/test_minimal/test_tools/test_ontology_brain_region_external_resources.py— no-op/gating cases, electrodes/group/imaging-plane annotation, metadata mapping + precedence, idempotency, extend-in-place, and a write→read round trip.Docs
docs/user_guide/brain_region_ontology.rst; theneuroconv.tools.ontologyAPI page picks up the new functions automatically.🤖 Generated with Claude Code